---
title: About package README files
---

We highly recommend including a `README.md` file in your package directory as it helps developers find your package on npm and have a good experience using your code in their projects. In most cases `README.md` files include directions for _installing_, _configuring_, and _using_ the code in your package; as well as any other information a user may find helpful. Just like in any GitHub repository, the `README.md` file will be rendered on the package's page.

An npm package `README.md` file **must** be in the root-level directory of the package.

## Creating and adding a `README.md` file to a package

1. In a text editor, in your package root directory, create a file called `README.md`.
2. In the `README.md` file, add useful information about your package.
3. Save the `README.md` file.

<Note>

**Note:** The file extension `.md` indicates a Markdown file. For more information about Markdown, see the GitHub Guide "[Mastering Markdown](https://guides.github.com/features/mastering-markdown/#what)".

</Note>

## Updating an existing package `README.md` file

The `README.md` file will only be updated on the package page when you publish a new version of your package. To update your `README.md` file:

1. In a text editor, update the contents of the `README.md` file.

2. Save the `README.md` file.

3. On the command line, in the package root directory, run the following commands:

   ```
   npm version patch
   npm publish
   ```

[markdown-link]: https://guides.github.com/features/mastering-markdown/#what
